/*
 * Copyright (c) 2007 jNetX.
 * http://www.jnetx.com
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of
 * jNetX. You shall not disclose such Confidential Information and
 * shall use it only in accordance with the terms of the license
 * agreement you entered into with jNetX.
 *
 * $Id$
 */
package com.jnetx.javax.sip.header;

import javax.sip.address.URI;
import javax.sip.header.CallInfoHeader;
import java.text.ParseException;

/**
 * The Call-Info header field provides additional information about the
 * caller or callee, depending on whether it is found in a request or
 * response.  The purpose of the URI is described by the "purpose"
 * parameter.  The "icon" purpose designates an image suitable as an
 * iconic representation of the caller or callee.  The "info" purpose
 * describes the caller or callee in general, for example, through a web
 * page.  The "card" purpose provides a business card, for example, in
 * vCard or LDIF formats.
 * <p/>
 * Use of the Call-Info header field can pose a security risk.  If a
 * callee fetches the URIs provided by a malicious caller, the callee
 * may be at risk for displaying inappropriate or offensive content,
 * dangerous or illegal content, and so on.  Therefore, it is
 * RECOMMENDED that a User Agent only render the information in the Call-Info
 * header field if it can verify the authenticity of the element that
 * originated the header field and trusts that element.  This need not
 * be the peer User Agent; a proxy can insert this header field into requests.
 * <p/>
 * For Example:<br>
 * <code>Call-Info: http://jcp.org/duke/photo.jpg;<br>
 * purpose=icon, http://jcp.org/duke/; purpose=info</code>
 *
 * @author <a href="mailto:dparhonin@jnetx.ru">Dmitry Parhonin</a>
 * @version $Revision$
 */
public class CallInfoHeaderImpl extends ParametrizedHeaderBase implements CallInfoHeader {
    private URI callInfo;

    private static final CallInfoHeaderParser parser = new CallInfoHeaderParser();

    public CallInfoHeaderImpl() {
        super(CallInfoHeader.NAME);
    }

    CallInfoHeaderImpl(byte[] data, int start, int end) {
        super(CallInfoHeader.NAME, data, start, end);
    }

    public Object clone() {
        final CallInfoHeaderImpl header = new CallInfoHeaderImpl();
        header.cloneBase(this);
        if (parsed) {
            header.cloneParameters(this);
            header.callInfo = this.callInfo;
        }
        return header;
    }

    protected HeaderParser getParser() {
        return parser;
    }

    protected String getValueAsString() {
        return '<' + callInfo.toString() + '>';
    }

    /**
     * Sets the Information parameter of this CallInfoHeader. The Information
     * describes the caller or callee.
     *
     * @param info the new URI value of the location of the information.
     */
    public void setInfo(URI info) {
        parse();
        this.callInfo = info;
        invalidateHeaderData();
    }

    /**
     * Gets the URI that represents the location of the info of the caller
     * or callee.
     *
     * @return the location of the info of this CallInfoHeader, returns null
     *         if no info is present.
     */
    public URI getInfo() {
        parse();
        return callInfo;
    }

    /**
     * Sets the purpose parameter of the info of this CallInfoHeader.
     *
     * @param purpose the new string value of the purpose of this info.
     * @throws java.text.ParseException which signals that an error has been reached
     *                                  unexpectedly while parsing the purpose value.
     */
    public void setPurpose(String purpose) throws ParseException {
        setParameter("purpose", purpose);
    }

    /**
     * Gets the purpose of the information supplied in this CallInfoHeader.
     *
     * @return the sting value of the purpose of the info, returns null
     *         if no purpose is present.
     */
    public String getPurpose() {
        return getParameter("purpose");
    }
}
/*
 * $Log$
 */